The "Knowledge in the Ether" Anti-Pattern

Shlomi Fish on 2007-04-17T16:15:24

One anti-pattern I noted in a previous workplace was what I called "Knowledge in the Ether": most of the instructions for getting the application up and running, and a lot of the collective knowledge were not written down in a collective place. TDDPirate said he was familiar with it and called it the "Oral Torah" syndrome.

The solution for this is simple: set up a wiki for the company, and instruct people to write a note there whenever they need to explain to someone how to do it (or give a link to a previous note), instead of guiding him how to do it. While this requires some discipline and getting used to, it can also be done after the fact.

Obviously the amount of knowledge in people's head and in the Ether can never be completely eliminated. But it should be kept down to a minimum.


Three strikes...

jplindstrom on 2007-04-17T18:00:18

...and then you automate.

Make sure part of the documentation process is typing it down in a scripting language.

Start out by just solving the immediate problem, then extracting out utility libraries and configuration patterns (make sure you do this, otherwise it will just end up being a mess of hardocded crap).

Soon it will be easier to script it than to document it.

Re:Three strikes...

Shlomi Fish on 2007-04-17T19:46:18

Yes, you're right. But documentation in a wiki still has its uses, including to point to the right script to use.